[1] 2
Writing functions in R
R for palaeobiologists: Workshop and Hackathon
takes input –> does something –> returns output
A function needs a name, arguments in (), and a body in {}
subtract <- function(arg1, arg2) {
arg1 - arg2
}
Imagine calculating the mean without standard functions like mean or sum:
Arguments need to be provided in the correct order, or specified by name:
Make function use more convenient, can hide complexities.
Additional, optional arguments can be allowed by using ‘…’ as the last argument:
A function generally should return something, but this does not:
Return explicitly with return, or place return value at the end of the function:
This did not work as intended. R functions only return one object. Instead use lists or other data structures:
Custom binary operators – let’s define an operator for “not in”:
if a condition is true, do something.
else instructs what to do when the if condition is not met.
Instead of many if and else statements, try switch
Loops are used for repeating similar actions multiple times. for loops iterate over a set of values. The iterator (i) changes with every iteration of the loop:
To generate sequences of integers, we can use seq_len. Let’s make a function:
while loops repeat a task until a condition is no longer met.
Create a function that can sort a data.frame into latitudinal bins. That is, we want a new column that identifies the bin of each entry of the data set. As an exemplary data set, we can use the reefs data from palaeoverse.
If you are new to writing R functions, try a simpler function that can sort data into the northern and southern hemisphere.
Here is what the result may look like when sorted into hemispheres:
Give variables and functions consistent names. These are the two most common styles:
Internal functions in R packages are often prefixed with a dot, e.g. .my_internal_function. Don’t prefix the file name with a dot.
Common practices:
Example of a detailed style guide: Tidyverse’s style guide
The lintr package let’s you check that your code conforms to your chosen standard.
Add some general information in the beginning of a large R script.
### Change point regression analysis
### July 2021
### Kilian Eichenseer
###
### Bayesian algorithm for finding a change point in
### the linear relationship between two variables.
### Uses JAGS (https://mcmc-jags.sourceforge.io/).
### Generate data
set.seed(10)
n <- 60 # total number of data pointsEven better: add formal documentation.
install.packages("roxygen2")’#This could generate documentation for the subtract function from earlier:
## roxygen2
Commonly used roxygen2 tags are:
For more details, see https://r-pkgs.org/man.html
roxygen2From RStudio, create a New Directory (File -> New Project...)
R folder as .R filesman folderNAMESPACE file once to avoid warningsWe start by installing roxygen2 and loading it:
To generate a documentation template for your function, click on Code --> Insert Roxygen Skeleton in Rstudio.
To generate documentation from our roxygen2 comments, which are denoted by the #' tags, run
or press Ctrl + Shift + D.
We can now read the documentation of our function by calling
Very helpful in complex functions
Check that input is correct and display custom error messages:
Use if you anticipate an error but want function to continue.
Let’s try to generate data from a multivariate normal distribution:
mvnfast::rmvn is fast but fails for some problematic sigma values. In case it fails, we use MASS::mvrnorm instead:
If something went wrong, find out where using traceback():
Break points allow you to look inside your function’s environment. Click next to a line of code in your function to activate a break point (a red dot appears):
You may need to run devtools::load_all() first.
We can now browse the function environment in the console like we normally can browse the global environment. For example we can look at sigma:
Press Stop to end the browsing. Don’t forget to deactivate the break point by clicking on the red dot in the script.
Functions should be tested before they are used.
Sometimes, interactive testing may be enough.
For example, identical() tests whether two objects are exactly equal:
install.packages("testthat")usethis::test_nameIn the test-subtract.R file, we can write tests, for example:
If we run this test, we should get
We can also run all of our tests at once with test_local or test_package("my_package"):
If you have the devtools package installed, you can also use devtools::test() by pressing Test in the Build tab of Rstudio:
Useful tests include:
For testing plot functions, the expect_doppelganger() function from the vdiffr package can be used:
This will create an image in the tests/testthat/_snaps/function_name directory. Upon first calling this, inspect the image to see if it is as expected. Future tests will fail if the function call in the test changes the image.
To check how much of your package is covered by tests, the covr package is helpful:
The report() function lets you check test coverage line by line:
testthat functionalitySetup for testing:
apply and related functions apply a function to elements of arrays, lists, …For example, to get the class of the first three columns of the reefs data:
Let’s have a look what happened there. apply(X, MARGIN, FUN) takes an array X (our reefs dataframe), and applies a function (FUN) to elements of that array, specified by MARGIN.
MARGIN = 2 indicates columns, MARGIN = 1 would be rows. So here we applied the class function to every column of reefs.
apply simplifies the output, so here it returned a vector with one element for each column.
lapply is similar to apply but for list or vector input. It returns a list for each element of the data.
vapply is a safer version of sapply, it requires the user to specify the anticipated class and length of the elements of the output:
Environment can be conceptualised as a place where objects with a name and value exist.
Each function, for loop, …, creates its own environment.
If we run the following function to assign to b the value of a
and then look for b in the global environment
we get an error because b only existed within the function environment.
More on environments: adv-r.hadley.nz/environments.html
R uses scoping rules to look for variables (or functions). If a variable is not found in a function environment, R looks in the parent environment (i.e. the environment in which the function was created).
x is a free variable in the double_x function – it is not supplied to or defined in the function. Instead, it’s looked up in the environment where double_x was created, the global environment.
This can get tricky, see here for more details: bookdown.org/rdpeng/rprogdatascience/scoping-rules-of-r.html
If you have large data sets and complex functions, you may want to enhance their performance.
The microbenchmark package performs an operation many times, and measures the average time it takes. You can also compare different operations.
The profvis package lets you identify bottlenecks in your code:
Only spend time trying to make your code faster if
Here is a good overview on making R functions run faster: Best coding practices in R
Pre-allocating memory is faster than growing objects repeatedly.
Assume, we have recorded the results of 1,000 dice rolls:
Let’s check which approach is faster:
Unit: microseconds
expr min lq mean median uq max neval
is_six_1(data) 1.5 1.6 4.2218 1.6 1.7 2545.0 1000
is_six_2(data) 1.0 1.1 3.4266 1.2 1.2 2246.7 1000
is_six_2() is faster, as R doesn’t have to grow the res object in every iteration.
R has many functions that are vectorised.
Unit: nanoseconds
expr min lq mean median uq max neval
is_six_2(data) 1000 1100 4301.1 1100 1200 3144200 1000
is_six_3(data) 200 200 1073.3 300 300 785900 1000
This time, the second version is much faster.
Vectorised matrix functions like rowSums(), colSums() or rowMeans()can lead to impressive speedups:
The Rcpp package allows for writing functions in C++. It requires the installation of a C++ compiler (R tools for Windows, Xcode for Mac, possibly “sudo apt-get install r-base-dev” on Linux)
Read more at Rcpp: Seamless R and C++ Integration orAvanced R
I also highly recommend ChatGpt for help with creating C++ functions.
As an example, let’s compare a random walk implemented in R with one implemented with Rcpp.
Next, the Rcpp version:
We now have the function random_walk_Rcpp in the global environment.
Let’s make sure both versions work:
Now let us compare the speed:
Loops are much faster in C++!
Comments
Good code shouldn’t need a large amount of comments - but comment enough that you can still use your code two years later.